Closes #450.

Summary

Adds docs/github-app-setup.md — the operator runbook for migrating from a classic-PAT credential profile to a GitHub App installation behind GitHubCredentialResolver.

This is only documentation. No code changes. The mode: 'app' code path has been live in inc/Support/GitHubCredentialResolver.php for some time; what was missing was a written-down procedure for actually performing the migration on a host.

What the runbook covers

• When to do this: bot identity, allowed_repos scoping, per-call token minting, removing single-human dependency.
• Prerequisites + concept primer: PAT vs App, how the resolver mints + caches installation tokens (JWT → installation access token → transient cache with 60s expiry skew).
• Step-by-step migration:
  1. Create the App on github.com with the permissions DMC actually uses (Contents read, Issues r/w, PRs r/w, Checks read, Statuses read, Actions read).
  2. Install the App on the org.
  3. Land the App ID + Installation ID + PEM private key on the host (PEM goes through the datamachine/update-settings ability so the sanitizer preserves newlines).
  4. Define github_credential_profiles with the App as default and the PAT demoted to a named fallback.
  5. Verify via wp datamachine-code github status.
  6. Smoke-test bot identity by filing a throwaway issue and confirming author_type: Bot via gh api.
  7. Test the PAT fallback path so operators know how to opt back into human identity when they need to.
• Troubleshooting: github_pat_not_configured on a wrongly-typed App profile, 401 from POST /app/installations/:id/access_tokens (App/install/PEM mismatch), poisoned token cache, openssl_sign() not available + the firebase/php-jwt fallback.
• Behavioral notes: per-call token minting, expiry skew, audit trail in the org log, when removing the PAT entirely makes sense.

Written from a live execution

Every command in the runbook was actually executed on extrachill.com against the Extra-Chill org's homeboy-ci App (app_id 3034937, installation_id 114752821). The smoke step was verified by filing Extra-Chill/extrachill-roadie#21 through datamachine/create-github-issue and confirming via gh api:

{"author":"homeboy-ci[bot]","author_type":"Bot","number":21,"state":"closed"}

So this runbook isn't theoretical — the procedure is exactly what worked.

Why DMC owns this doc

Per the discussion on #450: GitHubCredentialResolver, the mode: 'app' runtime, the datamachine/update-settings sanitizer for github_app_* fields, and wp datamachine-code github status all live in this plugin. Putting the runbook here means any DMC consumer (extrachill-roadie, future Studio integrations, CI tooling) has one canonical migration story to point at.

Out of scope (deferred / pre-existing follow-ups)

• Per-user GitHub OAuth. A team member with a linked GitHub account should commit/comment as themselves on GitHub. That lives in extrachill-users, not here.
• Removing the legacy single-cred surface entirely. The top-level github_pat / github_auth_mode / github_app_* settings still exist alongside github_credential_profiles. They coexist deliberately for back-compat; collapsing them is a separate cleanup.
• credential_selector plumbing through every issue/PR/comment ability. Some abilities accept the selector explicitly today, others rely on the default profile. Out of scope for this runbook; tracked separately if it needs filling in.

Notes for reviewer

• No CHANGELOG edit (homeboy owns release notes).
• Conventional commit (docs: ...).
• The runbook references concrete paths (/root/.secrets/<app-slug>.private-key.pem) and concrete numeric IDs (Extra-Chill's) as examples — those are documented as examples, not hardcoded. The procedure is org-neutral.